Generate a docs for properties that are a simple reference #5129
Conversation
|
Following you can find the validation changes against the target branch for the APIs. No changes detected. You can validate these APIs yourself by using the |
|
Thank you so much for this fix, @swallez! I asked the folks responsible for the docs generation process to verify if they can pick this change up correctly. I'll get back to you as soon as I have an answer. |
|
@swallez The folks at Bump pushed a modification on their side to support the new input. Just checked and your fix works fine! Thank you very much for your work, it significantly improves the API docs quality! 
Parameter descriptions like |
swallez
force-pushed
the
fix-property-docs
branch
from
525fb7c to
38aaed4
Compare
|
The backport to To backport manually, run these commands in your terminal: # Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.19 8.19
# Navigate to the new working tree
cd .worktrees/backport-8.19
# Create a new branch
git switch --create backport-5129-to-8.19
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 ef9f1da6e371f8681e1a603b6afc7637a0d704f0
# Push it to GitHub
git push --set-upstream origin backport-5129-to-8.19
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.19Then, create a pull request where the |
|
The backport to To backport manually, run these commands in your terminal: # Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.1 9.1
# Navigate to the new working tree
cd .worktrees/backport-9.1
# Create a new branch
git switch --create backport-5129-to-9.1
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 ef9f1da6e371f8681e1a603b6afc7637a0d704f0
# Push it to GitHub
git push --set-upstream origin backport-5129-to-9.1
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.1Then, create a pull request where the |
For properties, generate an allOf schema with descriptions instead of references
For properties, generate an allOf schema with descriptions instead of references
Open API 3.0 doesn't allow attaching docs and additional properties to a
$reftype definition. Because of this (and this was a forgottenTODO) many property descriptions were dropped in the OpenAPI output.This PR fixes this by using a common/recommended workaround consisting in using a single
allOfinline schema around the reference.Fixes #5082.
@szabosteve can you verify that the doc generation pipeline correctly picks up this change?
Example (taken from the diff):
Becomes: